<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>

    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta content="Cask Data, Inc." name="author" />
<meta content="HTTP RESTful Interface to the Cask Data Application Platform" name="description" />
<meta content="Copyright © 2014-2017 Cask Data, Inc." name="copyright" />


    <meta name="git_release" content="6.1.1">
    <meta name="git_hash" content="05fbac36f9f7aadeb44f5728cea35136dbc243e5">
    <meta name="git_timestamp" content="2020-02-09 08:22:47 +0800">
    <title>Lifecycle HTTP RESTful API</title>

    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/bootstrap-sphinx.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-dynamicscrollspy-4.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/cdap-jquery.mCustomScrollbar.css" type="text/css" />
    <link rel="stylesheet" href="../_static/css/abixTreeList-2.css" type="text/css" />
    <link rel="stylesheet" href="../_static/cdap-bootstrap.css" type="text/css" />

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '6.1.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>

    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="top" title="Cask Data Application Platform 6.1.1 Documentation" href="../index.html" />
    <link rel="up" title="CDAP HTTP RESTful API v3" href="index.html" />
    <link rel="next" title="Logging HTTP RESTful API" href="logging.html" />
    <link rel="prev" title="Dataset HTTP RESTful API" href="dataset.html" />
    <!-- block extrahead -->
    <meta charset='utf-8'>
    <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
    <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
    <meta name="apple-mobile-web-app-capable" content="yes">
    <!-- block extrahead end -->

</head>
<body role="document">

<!-- block navbar -->
<div id="navbar" class="navbar navbar-inverse navbar-default navbar-fixed-top">
    <div class="container-fluid">
      <div class="row">
        <div class="navbar-header">
          <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
          <a class="navbar-brand" href="../table-of-contents/../../index.html">
            <span><img alt="CDAP logo" src="../_static/cdap_logo.svg"/></span>
          </a>

          <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
          </button>

          <div class="pull-right">
            <div class="dropdown version-dropdown">
              <a href="#" class="dropdown-toggle" data-toggle="dropdown"
                role="button" aria-haspopup="true" aria-expanded="false">
                v 6.1.1 <span class="caret"></span>
              </a>
              <ul class="dropdown-menu">
                <li><a href="//docs.cdap.io/cdap/5.1.2/en/index.html">v 5.1.2</a></li>
                <li><a href="//docs.cdap.io/cdap/4.3.4/en/index.html">v 4.3.4</a></li>
              </ul>
            </div>
          </div>
          <form class="navbar-form navbar-right navbar-search" action="../search.html" method="get">
            <div class="form-group">
              <div class="navbar-search-image material-icons"></div>
              <input type="text" name="q" class="form-control" placeholder="  Search" />
            </div>
            <input type="hidden" name="check_keywords" value="yes" />
            <input type="hidden" name="area" value="default" />
          </form>

          <div class="collapse navbar-collapse nav-collapse navbar-right navbar-navigation">
            <ul class="nav navbar-nav"><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../index.html">简介</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../guides.html">手册</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link current" href="../table-of-contents/../../reference-manual/index.html">参考</a></li><li class="docsite-nav-tab-container"><a class="docsite-nav-tab-link " href="../table-of-contents/../../faqs/index.html">帮助</a></li>
            </ul>
          </div>

        </div>
      </div>
    </div>
  </div><!-- block navbar end -->
<!-- block main content -->
<div class="main-container container">
  <div class="row"><div class="col-md-2">
      <div id="sidebar" class="bs-sidenav scrollable-y-outside" role="complementary">
<!-- theme_manual: reference-manual -->
<!-- theme_manual_highlight: reference -->
<!-- sidebar_title_link: Reference -->

  <div role="note" aria-label="manuals links"><h3>Reference</h3>
    <ul class="reference-page-menu">
      <nav class="pagenav">
      <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html"> Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../characters.html"> Supported Characters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cli-api.html"> Command Line Interface API</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html"> HTTP RESTful API</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="artifact.html">Artifact</a></li>
<li class="toctree-l2"><a class="reference internal" href="configuration.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="dataset.html">Dataset</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="logging.html">Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="metadata.html">Metadata</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="monitor.html">Monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="namespace.html">Namespace</a></li>
<li class="toctree-l2"><a class="reference internal" href="dashboard.html">Dashboard</a></li>
<li class="toctree-l2"><a class="reference internal" href="preferences.html">Preferences</a></li>
<li class="toctree-l2"><a class="reference internal" href="profile.html">Profile</a></li>
<li class="toctree-l2"><a class="reference internal" href="query.html">Query</a></li>
<li class="toctree-l2"><a class="reference internal" href="reports.html">Reports</a></li>
<li class="toctree-l2"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l2"><a class="reference internal" href="service.html">Service</a></li>
<li class="toctree-l2"><a class="reference internal" href="transactions.html">Transactions</a></li>
<li class="toctree-l2"><a class="reference internal" href="workflow.html">Workflow</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../java-client-api.html"> Java Client API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../javadocs/index.html"> Javadocs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html"> 发行说明</a></li>
<li class="toctree-l1"><a class="reference internal" href="../licenses/index.html"> Trademarks, Licenses, and Dependencies</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html"> 术语表</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html"> Index</a></li>
</ul>
</nav>
    </ul>
  </div></div>
    </div><div class="col-md-8 content" id="main-content">
    
  <div class="section" id="lifecycle-http-restful-api">
<span id="http-restful-api-lifecycle"></span><h1>Lifecycle HTTP RESTful API<a class="headerlink" href="#lifecycle-http-restful-api" title="Permalink to this headline">🔗</a></h1>
<p>Use the CDAP Lifecycle HTTP RESTful API to deploy or delete applications and manage the lifecycle of
flows, MapReduce and Spark programs, custom services, workers, and workflows.</p>
<p>Details of these CDAP components can be found in the <a class="reference external" href="../../../developer-manual/building-blocks/index.html#building-blocks" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">开发手册: 核心概念</span></a>.</p>
<p>All methods or endpoints described in this API have a base URL (typically
<code class="docutils literal notranslate"><span class="pre">http://&lt;host&gt;:11015</span></code> or <code class="docutils literal notranslate"><span class="pre">https://&lt;host&gt;:10443</span></code>) that precedes the resource
identifier, as described in the <a class="reference internal" href="introduction.html#http-restful-api-conventions-base-url"><span class="std std-ref">RESTful API Conventions</span></a>.
These methods return a status code, as listed in the <a class="reference internal" href="introduction.html#http-restful-api-status-codes"><span class="std std-ref">RESTful API  Status Codes</span></a>.</p>
<div class="section" id="application-lifecycle">
<h2>Application Lifecycle<a class="headerlink" href="#application-lifecycle" title="Permalink to this headline">🔗</a></h2>
<div class="section" id="create-an-application">
<span id="http-restful-api-lifecycle-create-app"></span><h3>Create an Application<a class="headerlink" href="#create-an-application" title="Permalink to this headline">🔗</a></h3>
<p>To create an application, submit an HTTP PUT request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">PUT /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;</span>
</pre></div>
</div>
<p>To create an application with a non-default version, submit an HTTP POST request with the version specified:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/versions/&lt;version-id&gt;/create</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">version-id</span></code></td>
<td>Version of the application, typically following <a class="reference external" href="http://semver.org">semantic versioning</a>; versions ending with <code class="docutils literal notranslate"><span class="pre">-SNAPSHOT</span></code> can be overwritten</td>
</tr>
</tbody>
</table>
<p>The request body is a JSON object specifying the artifact to use to create the application,
and an optional application configuration. For example:</p>
<div class="highlight container">
<pre class="literal-block">
<span class="gp">$</span> PUT /v3/namespaces/default/apps/purchaseWordCount -d
{
  &quot;artifact&quot;: {
    &quot;name&quot;: &quot;WordCount&quot;,
    &quot;version&quot;: &quot;6.1.1&quot;,
    &quot;scope&quot;: &quot;user&quot;
  },
  &quot;config&quot;: {
    &quot;stream&quot;: &quot;purchaseStream&quot;
  },
  &quot;principal&quot;:&quot;<a class="reference external" href="mailto:user/example&#46;net&#37;&#52;&#48;EXAMPLEKDC&#46;NET">user/example<span>&#46;</span>net<span>&#64;</span>EXAMPLEKDC<span>&#46;</span>NET</a>&quot;,
  &quot;app.deploy.update.schedules&quot;:&quot;true&quot;
}
</pre>
</div>
<p>will create an application named <code class="docutils literal notranslate"><span class="pre">purchaseWordCount</span></code> from the example <code class="docutils literal notranslate"><span class="pre">WordCount</span></code> artifact.
The application will receive the specified <code class="docutils literal notranslate"><span class="pre">config</span></code>, which will configure the application
to create a stream named <code class="docutils literal notranslate"><span class="pre">purchaseStream</span></code> instead of using the default stream name.</p>
<p>Optionally, you can specify a Kerberos principal with which the application should be deployed.
If a Kerberos principal is specified, then all the streams and datasets created by the
application will be created with the application’s Kerberos principal.</p>
<p>Optionally, you can set or reset the flag <code class="docutils literal notranslate"><span class="pre">app.deploy.update.schedules</span></code>. If true,
redeploying an application will modify any schedules that currently exist for the application;
if false, redeploying an application does not create any new schedules and existing schedules
are neither deleted nor updated.</p>
</div>
<div class="section" id="update-an-application">
<h3>Update an Application<a class="headerlink" href="#update-an-application" title="Permalink to this headline">🔗</a></h3>
<p>To update an application, submit an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/update</span>
</pre></div>
</div>
<p>The request body is a JSON object specifying the updated artifact version and the updated application
config. For example, a request body of:</p>
<div class="highlight container">
<pre class="literal-block">
<span class="gp">$</span> POST /v3/namespaces/default/apps/purchaseWordCount/update -d
{
  &quot;artifact&quot;: {
    &quot;name&quot;: &quot;WordCount&quot;,
    &quot;version&quot;: &quot;6.1.1&quot;,
    &quot;scope&quot;: &quot;user&quot;
  },
  &quot;config&quot;: {
    &quot;stream&quot;: &quot;logStream&quot;;
  },
  &quot;principal&quot;:&quot;<a class="reference external" href="mailto:user/example&#46;net&#37;&#52;&#48;EXAMPLEKDC&#46;NET">user/example<span>&#46;</span>net<span>&#64;</span>EXAMPLEKDC<span>&#46;</span>NET</a>&quot;
}
</pre>
</div>
<p>will update the <code class="docutils literal notranslate"><span class="pre">purchaseWordCount</span></code> application to use version 6.1.1 of the <code class="docutils literal notranslate"><span class="pre">WordCount</span></code> artifact,
and update the name of the stream to <code class="docutils literal notranslate"><span class="pre">logStream</span></code>. If no artifact is given, the current artifact will be
used.</p>
<p>Only changes to artifact version are supported; changes to the artifact name are not allowed. If no
<code class="docutils literal notranslate"><span class="pre">config</span></code> is given, the current <code class="docutils literal notranslate"><span class="pre">config</span></code> will be used. If the <code class="docutils literal notranslate"><span class="pre">config</span></code> key is present, the current
<code class="docutils literal notranslate"><span class="pre">config</span></code> will be overwritten by the <code class="docutils literal notranslate"><span class="pre">config</span></code> specified in the request. As the principal of an
application cannot be updated, during an update the principal should either be the same or absent.</p>
</div>
<div class="section" id="deploy-an-artifact-and-application">
<h3>Deploy an Artifact and Application<a class="headerlink" href="#deploy-an-artifact-and-application" title="Permalink to this headline">🔗</a></h3>
<p>To deploy an application from your local file system into the namespace <em>namespace-id</em>,
submit an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps</span>
</pre></div>
</div>
<p>with the name of the JAR file as a header:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">X-Archive-Name: &lt;JAR filename&gt;</span>
</pre></div>
</div>
<p>and Kerberos principal with which the application is to be deployed (if required):</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">X-Principal: &lt;Kerberos Principal&gt;</span>
</pre></div>
</div>
<p>and enable or disable updating schedules of the existing workflows using the header:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">X-App-Deploy-Update-Schedules: &lt;Update Schedules&gt;</span>
</pre></div>
</div>
<p>This will add the JAR file as an artifact and then create an application from that artifact.
The archive name must be in the form <code class="docutils literal notranslate"><span class="pre">&lt;artifact-name&gt;-&lt;artifact-version&gt;.jar</span></code>.
An optional header can supply a configuration object as a serialized JSON string:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">X-App-Config: &lt;JSON Serialization String of the Configuration Object&gt;</span>
</pre></div>
</div>
<p>The application’s content is the body of the request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">&lt;JAR binary content&gt;</span>
</pre></div>
</div>
<p>Invoke the same command to update an application to a newer version.
However, be sure to stop all of its Spark and MapReduce programs before updating the application.</p>
<p>For an application that has a configuration class such as:</p>
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="kd">static</span> <span class="kd">class</span> <span class="nc">MyAppConfig</span> <span class="kd">extends</span> <span class="n">Config</span> <span class="p">{</span>
  <span class="n">String</span> <span class="n">streamName</span><span class="p">;</span>
  <span class="n">String</span> <span class="n">datasetName</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>We can deploy it with this RESTful call:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps</span>
<span class="go">-H &quot;X-Archive-Name: &lt;jar-name&gt;&quot; \</span>
<span class="go">-H &quot;X-Principal: &lt;kerberos-principal&gt;&quot; \</span>
<span class="go">-H &quot;X-App-Deploy-Update-Schedules: true&quot; \</span>
<span class="go">-H &#39;X-App-Config: &quot;{\&quot;streamName\&quot; : \&quot;newStream\&quot;, \&quot;datasetName\&quot; : \&quot;newDataset\&quot; }&quot; &#39; \</span>
<span class="go">--data-binary &quot;@&lt;jar-location&gt;&quot;</span>
</pre></div>
</div>
<p>Note that the <code class="docutils literal notranslate"><span class="pre">X-App-Config</span></code> header contains the JSON serialization string of the <code class="docutils literal notranslate"><span class="pre">MyAppConfig</span></code> object.</p>
</div>
<div class="section" id="deployed-applications">
<h3>Deployed Applications<a class="headerlink" href="#deployed-applications" title="Permalink to this headline">🔗</a></h3>
<p>To list all of the deployed applications in the namespace <em>namespace-id</em>, issue an HTTP
GET request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps[?artifactName=&lt;artifact-names&gt;[&amp;artifactVersion=&lt;artifact-version&gt;]]</span>
</pre></div>
</div>
<p>This will return a JSON String map that lists each application with its name, description, and artifact.
The list can optionally be filtered by one or more artifact names. It can also be filtered by artifact version.
For example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps?artifactName=cdap-data-pipeline,cdap-data-streams</span>
</pre></div>
</div>
<p>will return all applications that use either the <code class="docutils literal notranslate"><span class="pre">cdap-data-pipeline</span></code> or <code class="docutils literal notranslate"><span class="pre">cdap-data-streams</span></code> artifacts.</p>
</div>
<div class="section" id="details-of-a-deployed-application">
<span id="http-restful-api-lifecycle-app-deployed-details"></span><h3>Details of a Deployed Application<a class="headerlink" href="#details-of-a-deployed-application" title="Permalink to this headline">🔗</a></h3>
<p>For detailed information on an application that has been deployed in the namespace
<em>namespace-id</em>, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;</span>
</pre></div>
</div>
<p>The information will be returned in the body of the response. It includes the name and description
of the application; the artifact, streams, and datasets that it uses, all of its programs; and the
Kerberos principal, if that was provided during the deployment.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">200</span> <span class="pre">OK</span></code></td>
<td>The event successfully called the method, and the body contains the results</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="listing-versions-of-an-application">
<h3>Listing Versions of an Application<a class="headerlink" href="#listing-versions-of-an-application" title="Permalink to this headline">🔗</a></h3>
<p>To list all the versions of an application, submit an HTTP GET:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/versions</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
</tbody>
</table>
<p>The response will be a JSON array containing details about the application. The details
returned depend on the application.</p>
<p>For example, depending on the versions deployed:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/default/apps/SportResults/versions</span>
</pre></div>
</div>
<p>could return in a JSON array a list of the versions of the application:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s2">&quot;1.0.1&quot;</span><span class="p">,</span> <span class="s2">&quot;2.0.3&quot;</span><span class="p">]</span>
</pre></div>
</div>
</div>
<div class="section" id="delete-an-application">
<h3>Delete an Application<a class="headerlink" href="#delete-an-application" title="Permalink to this headline">🔗</a></h3>
<p>To delete an application—together with all of its MapReduce or Spark
programs, schedules, custom services, and workflows—submit an HTTP DELETE:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">DELETE /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;</span>
</pre></div>
</div>
<p>To delete a specific version of an application, submit an HTTP DELETE that includes the version:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">DELETE /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/versions/&lt;version-id&gt;</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application to be deleted</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">version-id</span></code></td>
<td>Version of the application to be deleted</td>
</tr>
</tbody>
</table>
<p><strong>Note:</strong> The <code class="docutils literal notranslate"><span class="pre">app-id</span></code> in this URL is the name of the application as
configured by the application specification, and not necessarily the same as the name of
the JAR file that was used to deploy the application.</p>
<p>This does not delete the streams and datasets associated with the application because they
belong to the namespace, not the application. Also, this does not delete the artifact used
to create the application.</p>
</div>
</div>
<div class="section" id="program-lifecycle">
<span id="http-restful-api-program-lifecycle"></span><h2>Program Lifecycle<a class="headerlink" href="#program-lifecycle" title="Permalink to this headline">🔗</a></h2>
<div class="section" id="details-of-a-program">
<h3>Details of a Program<a class="headerlink" href="#details-of-a-program" title="Permalink to this headline">🔗</a></h3>
<p>After an application is deployed, you can retrieve the details of its MapReduce and Spark programs,
custom services, schedules, workers, and workflows by submitting an HTTP GET request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;</span>
</pre></div>
</div>
<p>To retrieve information about the schedules of the program’s workflows, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workflows/&lt;workflow-id&gt;/schedules</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">workers</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflows</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">workflow-id</span></code></td>
<td>Name of the <em>workflow</em> being called, when retrieving schedules</td>
</tr>
</tbody>
</table>
<p>The response will be a JSON array containing details about the program. The details returned depend on the
program type.</p>
<p>For example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/default/apps/SportResults/services/UploadService</span>
</pre></div>
</div>
<p>will return in a JSON array information about the <em>UploadService</em> of the application <em>SportResults</em>. The results will
be similar to this (pretty-printed and portions deleted to fit):</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
    <span class="nt">&quot;className&quot;</span><span class="p">:</span> <span class="s2">&quot;io.cdap.cdap.examples.sportresults.UploadService&quot;</span><span class="p">,</span>
    <span class="nt">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;A service for uploading sport results for a given league and season.&quot;</span><span class="p">,</span>
    <span class="nt">&quot;handlers&quot;</span><span class="p">:</span> <span class="p">{</span>
        <span class="nt">&quot;UploadHandler&quot;</span><span class="p">:</span> <span class="p">{</span>
            <span class="nt">&quot;className&quot;</span><span class="p">:</span> <span class="s2">&quot;io.cdap.cdap.examples.sportresults.UploadService$UploadHandler&quot;</span><span class="p">,</span>
            <span class="nt">&quot;datasets&quot;</span><span class="p">:</span> <span class="p">[</span>
                <span class="s2">&quot;results&quot;</span>
            <span class="p">],</span>
            <span class="nt">&quot;description&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
            <span class="nt">&quot;endpoints&quot;</span><span class="p">:</span> <span class="p">[</span>
                <span class="p">{</span>
                    <span class="nt">&quot;method&quot;</span><span class="p">:</span> <span class="s2">&quot;PUT&quot;</span><span class="p">,</span>
                    <span class="nt">&quot;path&quot;</span><span class="p">:</span> <span class="s2">&quot;/leagues/{league}/seasons/{season}&quot;</span>
                <span class="p">},</span>
                <span class="c">...</span>
            <span class="p">],</span>
            <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;UploadHandler&quot;</span><span class="p">,</span>
            <span class="nt">&quot;plugins&quot;</span><span class="p">:</span> <span class="p">{},</span>
            <span class="nt">&quot;properties&quot;</span><span class="p">:</span> <span class="p">{}</span>
        <span class="p">}</span>
    <span class="p">},</span>
    <span class="nt">&quot;instances&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
    <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;UploadService&quot;</span><span class="p">,</span>
    <span class="nt">&quot;plugins&quot;</span><span class="p">:</span> <span class="p">{},</span>
    <span class="nt">&quot;resources&quot;</span><span class="p">:</span> <span class="p">{</span>
        <span class="nt">&quot;memoryMB&quot;</span><span class="p">:</span> <span class="mi">512</span><span class="p">,</span>
        <span class="nt">&quot;virtualCores&quot;</span><span class="p">:</span> <span class="mi">1</span>
    <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="start-a-program">
<span id="http-restful-api-lifecycle-start"></span><h3>Start a Program<a class="headerlink" href="#start-a-program" title="Permalink to this headline">🔗</a></h3>
<p>After an application is deployed, you can start its MapReduce and Spark programs,
custom services, workers, or workflows by submitting an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/start</span>
</pre></div>
</div>
<p>You can start a program of a particular version of the application by submitting an HTTP
POST request that includes the version:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/versions/&lt;version-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/start</span>
</pre></div>
</div>
<p>Note: Concurrent runs of workers across multiple versions of the same
application are not allowed.</p>
<p>When starting an program, you can optionally specify runtime arguments as a JSON map in
the request body. CDAP will use these runtime arguments only for this single invocation of
the program.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">version-id</span></code></td>
<td>Version of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">workers</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflows</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being called</td>
</tr>
</tbody>
</table>
<p><em>Flow</em>, <em>Service</em>, <em>Spark</em>, and <em>Worker</em> programs do not allow concurrent program runs.
Programs of these types cannot be started unless the program is in the <em>STOPPED</em> state.
<em>MapReduce</em> and <em>Workflow</em> programs support concurrent runs. If you start one of these programs,
a new run will be started even if other runs of the program have not finished yet.</p>
<p>For example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/default/apps/SportResults/services/UploadService/start -d &#39;{ &quot;foo&quot;:&quot;bar&quot;, &quot;this&quot;:&quot;that&quot; }&#39;</span>
</pre></div>
</div>
<p>will start the <em>UploadService</em> of the <em>SportResults</em> application with two runtime arguments.</p>
</div>
<div class="section" id="start-multiple-programs">
<span id="http-restful-api-lifecycle-start-multiple"></span><h3>Start Multiple Programs<a class="headerlink" href="#start-multiple-programs" title="Permalink to this headline">🔗</a></h3>
<p>You can start multiple programs from different applications and program types
by submitting an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/start</span>
</pre></div>
</div>
<p>with a JSON array in the request body consisting of multiple JSON objects with these parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">appId</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">programType</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">worker</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflow</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">programId</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being started</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">runtimeargs</span></code></td>
<td>Optional JSON object containing a string to string mapping of runtime arguments to start the program with</td>
</tr>
</tbody>
</table>
<p>The response will be a JSON array containing a JSON object for each object in the input.
Each JSON object will contain these parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">appId</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">programType</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">worker</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflow</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">programId</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being started</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">statusCode</span></code></td>
<td>The status code from starting an individual JSON object</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">error</span></code></td>
<td>If an error, a description of why the program could not be started (for example,
the specified program was not found)</td>
</tr>
</tbody>
</table>
<p>For example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/default/start -d &#39;</span>
<span class="go">  [</span>
<span class="go">    {&quot;appId&quot;: &quot;App1&quot;, &quot;programType&quot;: &quot;Service&quot;, &quot;programId&quot;: &quot;Service1&quot;},</span>
<span class="go">    {&quot;appId&quot;: &quot;App1&quot;, &quot;programType&quot;: &quot;Mapreduce&quot;, &quot;programId&quot;: &quot;MapReduce2&quot;},</span>
<span class="go">    {&quot;appId&quot;: &quot;App2&quot;, &quot;programType&quot;: &quot;Flow&quot;, &quot;programId&quot;: &quot;Flow1&quot;, &quot;runtimeargs&quot;: { &quot;arg1&quot;:&quot;val1&quot; }}</span>
<span class="go">  ]&#39;</span>
</pre></div>
</div>
<p>will attempt to start the three programs listed in the request body. It will return a response such as:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
  <span class="p">{</span><span class="nt">&quot;appId&quot;</span><span class="p">:</span> <span class="s2">&quot;App1&quot;</span><span class="p">,</span> <span class="nt">&quot;programType&quot;</span><span class="p">:</span> <span class="s2">&quot;Service&quot;</span><span class="p">,</span> <span class="nt">&quot;programId&quot;</span><span class="p">:</span> <span class="s2">&quot;Service1&quot;</span><span class="p">,</span> <span class="nt">&quot;statusCode&quot;</span><span class="p">:</span> <span class="mi">200</span><span class="p">},</span>
  <span class="p">{</span><span class="nt">&quot;appId&quot;</span><span class="p">:</span> <span class="s2">&quot;App1&quot;</span><span class="p">,</span> <span class="nt">&quot;programType&quot;</span><span class="p">:</span> <span class="s2">&quot;Mapreduce&quot;</span><span class="p">,</span> <span class="nt">&quot;programId&quot;</span><span class="p">:</span> <span class="s2">&quot;Mapreduce2&quot;</span><span class="p">,</span> <span class="nt">&quot;statusCode&quot;</span><span class="p">:</span> <span class="mi">200</span><span class="p">},</span>
  <span class="p">{</span><span class="nt">&quot;appId&quot;</span><span class="p">:</span> <span class="s2">&quot;App2&quot;</span><span class="p">,</span> <span class="nt">&quot;programType&quot;</span><span class="p">:</span><span class="s2">&quot;Flow&quot;</span><span class="p">,</span> <span class="nt">&quot;programId&quot;</span><span class="p">:</span><span class="s2">&quot;Flow1&quot;</span><span class="p">,</span> <span class="nt">&quot;statusCode&quot;</span><span class="p">:</span><span class="mi">404</span><span class="p">,</span> <span class="nt">&quot;error&quot;</span><span class="p">:</span> <span class="s2">&quot;App: App2 not found&quot;</span><span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
<p>In this particular example, the service and mapreduce programs in the <em>App1</em> application were successfully
started, and there was an error starting the last program because the <em>App2</em> application does not exist.</p>
</div>
<div class="section" id="stop-a-program">
<span id="http-restful-api-lifecycle-stop"></span><h3>Stop a Program<a class="headerlink" href="#stop-a-program" title="Permalink to this headline">🔗</a></h3>
<p>You can stop the MapReduce and Spark programs, custom services, workers, and
workflows of an application by submitting an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/stop</span>
</pre></div>
</div>
<p>You can stop the programs of a particular application version by submitting an HTTP POST
request that includes the version:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/versions/&lt;version-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/stop</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">version-id</span></code></td>
<td>Version of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">workers</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflows</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being stopped</td>
</tr>
</tbody>
</table>
<p>A program that is in the STOPPED state cannot be stopped. If there are multiple runs of the program
in the RUNNING state, this call will stop one of the runs, but not all of the runs.</p>
<p>For example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/default/apps/SportResults/services/UploadService/stop</span>
</pre></div>
</div>
<p>will stop the <em>UploadService</em> service in the <em>SportResults</em> application.</p>
</div>
<div class="section" id="stop-a-program-run">
<span id="http-restful-api-lifecycle-stop-run"></span><h3>Stop a Program Run<a class="headerlink" href="#stop-a-program-run" title="Permalink to this headline">🔗</a></h3>
<p>You can stop a specific run of a program by submitting an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/runs/&lt;run-id&gt;/stop</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">workers</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflows</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">run-id</span></code></td>
<td>Run id of the run being called</td>
</tr>
</tbody>
</table>
<p>For example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/default/apps/PurchaseHistory/mapreduce/PurchaseHistoryBuilder/runs/631bc459-a9dd-4218-9ea0-d46fb1991f82/stop</span>
</pre></div>
</div>
<p>will stop a specific run of the <em>PurchaseHistoryBuilder</em> MapReduce program in the <em>PurchaseHistory</em> application.</p>
</div>
<div class="section" id="stop-multiple-programs">
<span id="http-restful-api-lifecycle-stop-multiple"></span><h3>Stop Multiple Programs<a class="headerlink" href="#stop-multiple-programs" title="Permalink to this headline">🔗</a></h3>
<p>You can stop multiple programs from different applications and program types
by submitting an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/stop</span>
</pre></div>
</div>
<p>with a JSON array in the request body consisting of multiple JSON objects with these parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">appId</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">programType</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">worker</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflow</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">programId</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being stopped</td>
</tr>
</tbody>
</table>
<p>The response will be a JSON array containing a JSON object corresponding to each object in the input.
Each JSON object will contain these parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">appId</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">programType</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">worker</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflow</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">programId</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being stopped</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">statusCode</span></code></td>
<td>The status code from stopping an individual JSON object</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">error</span></code></td>
<td>If an error, a description of why the program could not be stopped (for example,
the specified program was not found)</td>
</tr>
</tbody>
</table>
<p>For example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/default/stop -d &#39;</span>
<span class="go">  [</span>
<span class="go">    {&quot;appId&quot;: &quot;App1&quot;, &quot;programType&quot;: &quot;Service&quot;, &quot;programId&quot;: &quot;Service1&quot;},</span>
<span class="go">    {&quot;appId&quot;: &quot;App1&quot;, &quot;programType&quot;: &quot;Mapreduce&quot;, &quot;programId&quot;: &quot;MapReduce2&quot;},</span>
<span class="go">    {&quot;appId&quot;: &quot;App2&quot;, &quot;programType&quot;: &quot;Flow&quot;, &quot;programId&quot;: &quot;Flow1&quot;}</span>
<span class="go">  ]&#39;</span>
</pre></div>
</div>
<p>will attempt to stop the three programs listed in the request body. It will return a response such as:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
  <span class="p">{</span><span class="nt">&quot;appId&quot;</span><span class="p">:</span> <span class="s2">&quot;App1&quot;</span><span class="p">,</span> <span class="nt">&quot;programType&quot;</span><span class="p">:</span> <span class="s2">&quot;Service&quot;</span><span class="p">,</span> <span class="nt">&quot;programId&quot;</span><span class="p">:</span> <span class="s2">&quot;Service1&quot;</span><span class="p">,</span> <span class="nt">&quot;statusCode&quot;</span><span class="p">:</span> <span class="mi">200</span><span class="p">},</span>
  <span class="p">{</span><span class="nt">&quot;appId&quot;</span><span class="p">:</span> <span class="s2">&quot;App1&quot;</span><span class="p">,</span> <span class="nt">&quot;programType&quot;</span><span class="p">:</span> <span class="s2">&quot;Mapreduce&quot;</span><span class="p">,</span> <span class="nt">&quot;programId&quot;</span><span class="p">:</span> <span class="s2">&quot;Mapreduce2&quot;</span><span class="p">,</span> <span class="nt">&quot;statusCode&quot;</span><span class="p">:</span> <span class="mi">200</span><span class="p">},</span>
  <span class="p">{</span><span class="nt">&quot;appId&quot;</span><span class="p">:</span> <span class="s2">&quot;App2&quot;</span><span class="p">,</span> <span class="nt">&quot;programType&quot;</span><span class="p">:</span><span class="s2">&quot;Flow&quot;</span><span class="p">,</span> <span class="nt">&quot;programId&quot;</span><span class="p">:</span><span class="s2">&quot;Flow1&quot;</span><span class="p">,</span> <span class="nt">&quot;statusCode&quot;</span><span class="p">:</span><span class="mi">404</span><span class="p">,</span> <span class="nt">&quot;error&quot;</span><span class="p">:</span> <span class="s2">&quot;App: App2 not found&quot;</span><span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
<p>In this particular example, the service and mapreduce programs in the <em>App1</em> application were successfully
stopped, and there was an error starting the last program because the <em>App2</em> application does not exist.</p>
</div>
<div class="section" id="status-of-a-program">
<span id="http-restful-api-lifecycle-status"></span><h3>Status of a Program<a class="headerlink" href="#status-of-a-program" title="Permalink to this headline">🔗</a></h3>
<p>To retrieve the status of a program, submit an HTTP GET request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/status</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">schedules</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">workers</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflows</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>schedule</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being called</td>
</tr>
</tbody>
</table>
<p>The response will be a JSON array with status of the program. For example, retrieving the status of the
<em>UploadService</em> of the program <em>SportResults</em>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/default/apps/SportResults/services/UploadService/status</span>
</pre></div>
</div>
<p>will return (pretty-printed) a response such as:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
    <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;STOPPED&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="status-of-multiple-programs">
<span id="http-restful-api-lifecycle-status-multi"></span><h3>Status of Multiple Programs<a class="headerlink" href="#status-of-multiple-programs" title="Permalink to this headline">🔗</a></h3>
<p>You can retrieve the status of multiple programs from different applications and program types
by submitting an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/status</span>
</pre></div>
</div>
<p>with a JSON array in the request body consisting of multiple JSON objects with these parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">appId</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">programType</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">schedule</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">worker</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflow</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">programId</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>schedule</em>, <em>custom service</em>, <em>Spark</em>, <em>worker</em>, or <em>workflow</em>
being called</td>
</tr>
</tbody>
</table>
<p>The response will be the same JSON array as submitted with additional parameters for each
of the underlying JSON objects:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">status</span></code></td>
<td>Maps to the status of an individual JSON object’s queried program
if the query is valid and the program was found</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">statusCode</span></code></td>
<td>The status code from retrieving the status of an individual JSON object</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">error</span></code></td>
<td>If an error, a description of why the status was not retrieved (for example, the specified program was not found)</td>
</tr>
</tbody>
</table>
<p>The <code class="docutils literal notranslate"><span class="pre">status</span></code> and <code class="docutils literal notranslate"><span class="pre">error</span></code> fields are mutually exclusive meaning if there is an error,
then there will never be a status and vice versa.</p>
<p>For example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/default/status -d &#39;</span>
<span class="go">  [</span>
<span class="go">    { &quot;appId&quot;: &quot;MyApp&quot;, &quot;programType&quot;: &quot;flow&quot;, &quot;programId&quot;: &quot;MyFlow&quot; },</span>
<span class="go">    { &quot;appId&quot;: &quot;MyApp2&quot;, &quot;programType&quot;: &quot;service&quot;, &quot;programId&quot;: &quot;MyService&quot; }</span>
<span class="go">  ]</span>
</pre></div>
</div>
<p>will retrieve the status of two programs. It will return a response such as:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
  <span class="p">{</span> <span class="nt">&quot;appId&quot;</span><span class="p">:</span><span class="s2">&quot;MyApp&quot;</span><span class="p">,</span> <span class="nt">&quot;programType&quot;</span><span class="p">:</span><span class="s2">&quot;flow&quot;</span><span class="p">,</span> <span class="nt">&quot;programId&quot;</span><span class="p">:</span><span class="s2">&quot;MyFlow&quot;</span><span class="p">,</span> <span class="nt">&quot;status&quot;</span><span class="p">:</span><span class="s2">&quot;RUNNING&quot;</span><span class="p">,</span> <span class="nt">&quot;statusCode&quot;</span><span class="p">:</span><span class="mi">200</span> <span class="p">},</span>
  <span class="p">{</span> <span class="nt">&quot;appId&quot;</span><span class="p">:</span><span class="s2">&quot;MyApp2&quot;</span><span class="p">,</span> <span class="nt">&quot;programType&quot;</span><span class="p">:</span><span class="s2">&quot;service&quot;</span><span class="p">,</span> <span class="nt">&quot;programId&quot;</span><span class="p">:</span><span class="s2">&quot;MyService&quot;</span><span class="p">,</span> <span class="nt">&quot;error&quot;</span><span class="p">:</span><span class="s2">&quot;Program not found&quot;</span><span class="p">,</span> <span class="nt">&quot;statusCode&quot;</span><span class="p">:</span><span class="mi">404</span> <span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="schedule-lifecycle">
<span id="http-restful-api-lifecycle-schedule"></span><h2>Schedule Lifecycle<a class="headerlink" href="#schedule-lifecycle" title="Permalink to this headline">🔗</a></h2>
<p>Currently (as of CDAP 6.1.1), schedules can only be created for <a class="reference external" href="../../../developer-manual/building-blocks/workflows.html#workflows" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">workflows</span></a>. Future releases of CDAP will expand this to encompass other program types.</p>
<div class="section" id="add-a-schedule">
<span id="http-restful-api-lifecycle-schedule-add"></span><h3>Add a Schedule<a class="headerlink" href="#add-a-schedule" title="Permalink to this headline">🔗</a></h3>
<p>To add a schedule for a program to an application, submit an HTTP PUT request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">PUT /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/schedules/&lt;schedule-id&gt;</span>
</pre></div>
</div>
<p>To add the schedule to an application with a non-default version, submit an HTTP PUT
request with the version specified:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">PUT /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/versions/&lt;version-id&gt;/schedules/&lt;schedule-id&gt;</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">schedule-id</span></code></td>
<td>Name of the schedule; it is unique to the application and, if specified, the
application version</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">version-id</span></code></td>
<td>Version of the application, typically following <a class="reference external" href="http://semver.org">semantic versioning</a></td>
</tr>
</tbody>
</table>
<p>The request body is a JSON object specifying the details of the schedule to be created:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;name&quot;: &quot;&lt;name of the schedule&gt;&quot;,</span>
<span class="go">  &quot;description&quot;: &quot;&lt;schedule description&gt;&quot;,</span>
<span class="go">  &quot;namespace&quot;: &quot;&lt;namespace of the schedule&gt;&quot;,</span>
<span class="go">  &quot;application&quot;: &quot;&lt;application of the schedule&gt;&quot;,</span>
<span class="go">  &quot;applicationVersion&quot;: &quot;&lt;application version of the schedule&gt;&quot;,</span>
<span class="go">  &quot;program&quot;: {</span>
<span class="go">    &quot;programName&quot;: &quot;&lt;name of the program&gt;&quot;,</span>
<span class="go">    &quot;programType&quot;: &quot;WORKFLOW&quot;</span>
<span class="go">  },</span>
<span class="go">  &quot;properties&quot;: {</span>
<span class="go">    &quot;&lt;key&gt;&quot;: &quot;&lt;value&gt;&quot;,</span>
<span class="go">    ...</span>
<span class="go">  },</span>
<span class="go">  &quot;constraints&quot;: [</span>
<span class="go">    {</span>
<span class="go">      &quot;type&quot;: &quot;&lt;constraint type&gt;&quot;,</span>
<span class="go">      &quot;waitUntilMet&quot;: &lt;boolean&gt;,</span>
<span class="go">      ...</span>
<span class="go">    },</span>
<span class="go">    ...</span>
<span class="go">  ],</span>
<span class="go">  &quot;trigger&quot;: {</span>
<span class="go">    &quot;type&quot;: &quot;&lt;trigger type&gt;&quot;,</span>
<span class="go">    ...</span>
<span class="go">  },</span>
<span class="go">  &quot;timeoutMillis&quot;: &lt;timeout in milliseconds&gt;</span>
<span class="go">}</span>
</pre></div>
</div>
<p>where a trigger is of one of the <a class="reference external" href="../../../developer-manual/building-blocks/schedules.html#schedules-triggers" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">trigger types</span></a>.
It can be a time trigger:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;type&quot;: &quot;TIME&quot;,</span>
<span class="go">  &quot;cronExpression&quot;: &quot;&lt;cron expression&gt;&quot;</span>
<span class="go">}</span>
</pre></div>
</div>
<p>or a partition trigger:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;type&quot;: &quot;PARTITION&quot;,</span>
<span class="go">  &quot;dataset&quot;: {</span>
<span class="go">    &quot;namespace&quot;: &quot;&lt;namespace of the dataset&gt;&quot;,</span>
<span class="go">    &quot;dataset&quot;: &quot;&lt;name of the dataset&gt;&quot;</span>
<span class="go">  },</span>
<span class="go">  &quot;numPartitions&quot;: &lt;required number of partitions&gt;</span>
<span class="go">}</span>
</pre></div>
</div>
<p>or a program status trigger:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;programId&quot;: {</span>
<span class="go">      &quot;namespace&quot;: &quot;&lt;namespace of the program&gt;&quot;,</span>
<span class="go">      &quot;application&quot;: &quot;&lt;application name of the program&gt;&quot;,</span>
<span class="go">      &quot;version&quot;: &quot;&lt;application version of the program&gt;&quot;,</span>
<span class="go">      &quot;type&quot;: &quot;&lt;type of the program&gt;&quot;,</span>
<span class="go">      &quot;entity&quot;: &quot;PROGRAM&quot;,</span>
<span class="go">      &quot;program&quot;: &quot;&lt;name of the program&gt;&quot;</span>
<span class="go">  },</span>
<span class="go">  &quot;programStatuses&quot;: [ &lt;COMPLETED&gt;, &lt;FAILED&gt;, &lt;KILLED&gt; ],</span>
<span class="go">  &quot;type&quot;: &quot;PROGRAM_STATUS&quot;</span>
<span class="go">}</span>
</pre></div>
</div>
<p>or an <cite>and</cite> trigger, where “triggers” is a non-empty list of any type of triggers:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;triggers&quot; : [</span>
<span class="go">    {</span>
<span class="go">      &quot;type&quot;: &quot;&lt;trigger type&gt;&quot;,</span>
<span class="go">      ...</span>
<span class="go">    },</span>
<span class="go">    ...</span>
<span class="go">  ],</span>
<span class="go">  &quot;type&quot;: &quot;AND&quot;</span>
<span class="go">}</span>
</pre></div>
</div>
<p>or an <cite>or</cite> trigger, where “triggers” is a non-empty list of any type of triggers:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;triggers&quot; : [</span>
<span class="go">    {</span>
<span class="go">      &quot;type&quot;: &quot;&lt;trigger type&gt;&quot;,</span>
<span class="go">      ...</span>
<span class="go">    },</span>
<span class="go">    ...</span>
<span class="go">  ],</span>
<span class="go">  &quot;type&quot;: &quot;OR&quot;</span>
<span class="go">}</span>
</pre></div>
</div>
<p>and a constraint can be one of:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{</span>
<span class="go">  &quot;type&quot;: &quot;CONCURRENCY&quot;,</span>
<span class="go">  &quot;maxConcurrency&quot;: &lt;max number of runs&gt;,</span>
<span class="go">  &quot;waitUntilMet&quot;: &lt;boolean&gt;</span>
<span class="go">}</span>

<span class="go">{</span>
<span class="go">  &quot;type&quot;: &quot;DELAY&quot;,</span>
<span class="go">  &quot;millisAfterTrigger&quot;: &lt;milliseconds to delay&gt;,</span>
<span class="go">  &quot;waitUntilMet&quot;: &lt;boolean&gt;</span>
<span class="go">}</span>

<span class="go">{</span>
<span class="go">  &quot;type&quot;: &quot;TIME_RANGE&quot;,</span>
<span class="go">  &quot;startTime&quot;: &quot;&lt;time in form HH:mm&gt;&quot;,</span>
<span class="go">  &quot;endTime&quot;: &quot;&lt;time in form HH:mm&gt;&quot;,</span>
<span class="go">  &quot;timeZone&quot;: &quot;&lt;name of the time zone, e.g., PST&gt;&quot;,</span>
<span class="go">  &quot;waitUntilMet&quot;: &lt;boolean&gt;</span>
<span class="go">}</span>

<span class="go">{</span>
<span class="go">  &quot;type&quot;: &quot;LAST_RUN&quot;,</span>
<span class="go">  &quot;millisSinceLastRun&quot;: &lt;milliseconds since last run&gt;,</span>
<span class="go">  &quot;waitUntilMet&quot;: &lt;boolean&gt;</span>
<span class="go">}</span>
</pre></div>
</div>
<p><em>Note:</em> For any schedule, the program must be for a workflow and the <code class="docutils literal notranslate"><span class="pre">programType</span></code> must be set to <code class="docutils literal notranslate"><span class="pre">WORKLFLOW</span></code>.</p>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">409</span> <span class="pre">Conflict</span></code></td>
<td>Schedule with the same name already exists</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="update-a-schedule">
<span id="http-restful-api-lifecycle-schedule-update"></span><h3>Update a Schedule<a class="headerlink" href="#update-a-schedule" title="Permalink to this headline">🔗</a></h3>
<p>To update a schedule, submit an HTTP POST request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/schedules/&lt;schedule-id&gt;/update</span>
</pre></div>
</div>
<p>To update a schedule of an application with a non-default version, submit an HTTP POST
request with the version specified:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/versions/&lt;version-id&gt;/schedules/&lt;schedule-id&gt;/update</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">schedule-id</span></code></td>
<td>Name of the schedule; it is unique to the application and, if specified, the
application version</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">version-id</span></code></td>
<td>Version of the application, typically following <a class="reference external" href="http://semver.org">semantic versioning</a></td>
</tr>
</tbody>
</table>
<p>The request body is a JSON object specifying the details of the schedule to be updated, and follows
the same form as documented in <a class="reference internal" href="#http-restful-api-lifecycle-schedule-add"><span class="std std-ref">Add a Schedule</span></a>.</p>
<p>Only changes to the schedule configurations are supported; changes to the schedule name, or to the
program associated with it are not allowed. If <em>any</em> properties are provided, they will
overwrite all existing properties with what is provided. You must include all
properties, even ones you are are not altering.</p>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">400</span> <span class="pre">Bad</span> <span class="pre">Request</span></code></td>
<td>If the new schedule type does not match the existing schedule type or there are
other client errors</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="retrieving-a-schedule">
<span id="http-restful-api-lifecycle-schedule-list"></span><h3>Retrieving a Schedule<a class="headerlink" href="#retrieving-a-schedule" title="Permalink to this headline">🔗</a></h3>
<p>To retrieve a schedule in an application, submit an HTTP GET request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/schedules/&lt;schedule-name&gt;</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">schedule-name</span></code></td>
<td>Name of the schedule</td>
</tr>
</tbody>
</table>
<p>The response will contain the schedule in the same form described in <a class="reference internal" href="#http-restful-api-lifecycle-schedule-add"><span class="std std-ref">Add a Schedule</span></a>.</p>
</div>
<div class="section" id="list-schedules">
<h3>List Schedules<a class="headerlink" href="#list-schedules" title="Permalink to this headline">🔗</a></h3>
<p>To list all of the schedules for an application, use an HTTP GET request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/schedules</span>
</pre></div>
</div>
<p>As schedules are created for a workflow, you can also list schedules for a workflow of an application.
You can use the <a class="reference internal" href="#http-restful-api-lifecycle-app-deployed-details"><span class="std std-ref">Details of a Deployed Application</span></a> to obtain the workflows of an
application.</p>
<p>To list all of the schedules of a workflow of an application, use an HTTP GET request:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workflows/&lt;workflow-id&gt;/schedules</span>
</pre></div>
</div>
<p>The response will contain a list of schedules in the same form as described
in <a class="reference internal" href="#http-restful-api-lifecycle-schedule-add"><span class="std std-ref">Add a Schedule</span></a>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">workflow-id</span></code></td>
<td>Name of the workflow</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="next-scheduled-run-time">
<h3>Next Scheduled Run Time<a class="headerlink" href="#next-scheduled-run-time" title="Permalink to this headline">🔗</a></h3>
<p>To list the next time that the workflow will be be scheduled by a time trigger,
use the parameter <code class="docutils literal notranslate"><span class="pre">nextruntime</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workflows/&lt;workflow-id&gt;/nextruntime</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">workflow-id</span></code></td>
<td>Name of the workflow</td>
</tr>
</tbody>
</table>
<div class="table-block-example container">
<table border="1" class="docutils">
<colgroup>
<col width="99%" />
<col width="1%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">Example: Retrieving The Next Runtime</th>
<td>&#160;</td>
</tr>
</tbody>
</table>
<table border="1" class="triple-table docutils">
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Description</td>
<td>Retrieves the next runtime of the workflow <em>PurchaseHistoryWorkflow</em> of the
application <em>PurchaseHistory</em></td>
</tr>
<tr class="row-even"><td>HTTP Method</td>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/namespaces/default/apps/PurchaseHistory/workflows/PurchaseHistoryWorkflow/nextruntime</span></code></td>
</tr>
<tr class="row-odd"><td>Returns</td>
<td><div class="first last line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[{&quot;id&quot;:&quot;DEFAULT.WORKFLOW:developer:PurchaseHistory:PurchaseHistoryWorkflow:0:DailySchedule&quot;,&quot;time&quot;:1415102400000}]</span></code></div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="delete-a-schedule">
<span id="http-restful-api-lifecycle-schedule-delete"></span><h3>Delete a Schedule<a class="headerlink" href="#delete-a-schedule" title="Permalink to this headline">🔗</a></h3>
<p>To delete a schedule, submit an HTTP DELETE:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">DELETE /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/schedules/&lt;schedule-id&gt;</span>
</pre></div>
</div>
<p>To delete a schedule of an application with a non-default version, submit an HTTP DELETE
request with the version specified:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">DELETE /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/versions/&lt;version-id&gt;/schedules/&lt;schedule-id&gt;</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application to be deleted</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">schedule-id</span></code></td>
<td>Name of the schedule; it is unique to the application and, if specified, the
application version</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">version-id</span></code></td>
<td>Version of the application to be deleted</td>
</tr>
</tbody>
</table>
<p class="rubric">HTTP Responses</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Status Codes</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Bad</span> <span class="pre">Request</span></code></td>
<td>If the schedule given by <code class="docutils literal notranslate"><span class="pre">schedule-id</span></code> was not found</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="schedule-disable-and-and-enable">
<span id="http-restful-api-lifecycle-schedule-disable-enable"></span><h3>Schedule: Disable and and Enable<a class="headerlink" href="#schedule-disable-and-and-enable" title="Permalink to this headline">🔗</a></h3>
<p>For a schedule, you can disable and enable it using the RESTful API.</p>
<p><strong>Disable:</strong> To <em>disable</em> a schedule means that the program associated with that schedule will not
trigger again until the schedule is enabled.</p>
<p><strong>Enable:</strong> To <em>enable</em> a schedule means that the trigger is reset, and the program associated will
run again at the next scheduled time.</p>
<p>As a schedule is initially deployed in a <em>disabled</em> state, a call to this API is needed to <em>enable</em> it.</p>
<p>To disable or enable a schedule use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/schedules/&lt;schedule-id&gt;/disable</span>
<span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/schedules/&lt;schedule-id&gt;/enable</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">schedule-id</span></code></td>
<td>Name of the schedule</td>
</tr>
</tbody>
</table>
<div class="table-block-example container">
<table border="1" class="docutils">
<colgroup>
<col width="99%" />
<col width="1%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">Example: Disabling a Schedule</th>
<td>&#160;</td>
</tr>
</tbody>
</table>
<table border="1" class="triple-table docutils">
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Description</td>
<td>Disables the schedule <em>DailySchedule</em> of the application <em>PurchaseHistory</em></td>
</tr>
<tr class="row-even"><td>HTTP Method</td>
<td><code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/v3/namespaces/default/apps/PurchaseHistory/schedules/DailySchedule/disable</span></code></td>
</tr>
<tr class="row-odd"><td>Returns</td>
<td><div class="first last line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">OK</span></code> if successfully set as disabled</div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="section" id="container-information">
<span id="http-restful-api-lifecycle-container-information"></span><h2>Container Information<a class="headerlink" href="#container-information" title="Permalink to this headline">🔗</a></h2>
<p>To find out the address of an program’s container host and the container’s debug port, you can query
CDAP for a service’s live info via an HTTP GET method:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/live-info</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, or  <code class="docutils literal notranslate"><span class="pre">workers</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the program (<em>flow</em>, <em>service</em>, or <em>worker</em>)</td>
</tr>
</tbody>
</table>
<p>Example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/default/apps/WordCount/flows/WordCounter/live-info</span>
</pre></div>
</div>
<p>The response is formatted in JSON; an example of this is shown in
<a class="reference external" href="../../../developer-manual/testing/debugging.html#debugging-distributed" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">CDAP Testing and Debugging</span></a>.</p>
</div>
<div class="section" id="scaling">
<span id="http-restful-api-lifecycle-scale"></span><h2>Scaling<a class="headerlink" href="#scaling" title="Permalink to this headline">🔗</a></h2>
<p>You can retrieve the instance count executing different components from various applications and
different program types using an HTTP POST method:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/instances</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
</tbody>
</table>
<p>with a JSON array in the request body consisting of multiple JSON objects with these parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">appId</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">programType</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, or <code class="docutils literal notranslate"><span class="pre">worker</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">programId</span></code></td>
<td>Name of the program (<em>flow</em>, <em>service</em>, or <em>worker</em>) being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">runnableId</span></code></td>
<td>Name of the <em>flowlet</em>, only required if the program type is <code class="docutils literal notranslate"><span class="pre">flow</span></code></td>
</tr>
</tbody>
</table>
<p>The response will be the same JSON array as submitted with additional parameters for each
of the underlying JSON objects:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">requested</span></code></td>
<td>Number of instances the user requested for the program defined by the individual JSON object’s parameters</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">provisioned</span></code></td>
<td>Number of instances that are actually running for the program defined by the individual JSON object’s parameters.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">statusCode</span></code></td>
<td>The status code from retrieving the instance count of an individual JSON object</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">error</span></code></td>
<td>If an error, a description of why the status was not retrieved (for example, the
specified program was not found, or the requested JSON object was missing a parameter)</td>
</tr>
</tbody>
</table>
<p><strong>Note:</strong> The <code class="docutils literal notranslate"><span class="pre">requested</span></code> and <code class="docutils literal notranslate"><span class="pre">provisioned</span></code> fields are mutually exclusive of the <code class="docutils literal notranslate"><span class="pre">error</span></code> field.</p>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Method</th>
<td><code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/v3/namespaces/default/instances</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Body</th>
<td><code class="docutils literal notranslate"><span class="pre">[{&quot;appId&quot;:&quot;MyApp1&quot;,&quot;programType&quot;:&quot;Flow&quot;,&quot;programId&quot;:&quot;MyFlow1&quot;,&quot;runnableId&quot;:&quot;MyFlowlet5&quot;},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:&quot;MyApp3&quot;,&quot;programType&quot;:&quot;Service&quot;,&quot;programId&quot;:&quot;MySvc1,&quot;runnableId&quot;:&quot;MyHandler1&quot;}]</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">HTTP Response</th>
<td><code class="docutils literal notranslate"><span class="pre">[{&quot;appId&quot;:&quot;MyApp1&quot;,&quot;programType&quot;:&quot;Flow&quot;,&quot;programId&quot;:&quot;MyFlow1&quot;,</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;runnableId&quot;:&quot;MyFlowlet5&quot;,&quot;provisioned&quot;:2,&quot;requested&quot;:2,&quot;statusCode&quot;:200},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:&quot;MyApp3&quot;,&quot;programType&quot;:&quot;Service&quot;,&quot;programId&quot;:&quot;MySvc1,</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;runnableId&quot;:&quot;MyHandler1&quot;,&quot;statusCode&quot;:404,&quot;error&quot;:&quot;Runnable:</span> <span class="pre">MyHandler1</span> <span class="pre">not</span> <span class="pre">found&quot;}]</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Description</th>
<td>Attempt to retrieve the instances of the flowlet <em>MyFlowlet5</em> in the flow <em>MyFlow1</em> in the
application <em>MyApp1</em>, and the service handler <em>MyHandler1</em> in the user service
<em>MySvc1</em> in the application <em>MyApp3</em>, all in the namespace <em>default</em></td>
</tr>
</tbody>
</table>
<div class="section" id="scaling-flowlets">
<span id="rest-scaling-flowlets"></span><h3>Scaling Flowlets<a class="headerlink" href="#scaling-flowlets" title="Permalink to this headline">🔗</a></h3>
<p>You can query and set the number of instances executing a given flowlet
by using the <code class="docutils literal notranslate"><span class="pre">instances</span></code> parameter with HTTP GET and PUT methods:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/flows/&lt;flow-id&gt;/flowlets/&lt;flowlet-id&gt;/instances</span>
<span class="go">PUT /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/flows/&lt;flow-id&gt;/flowlets/&lt;flowlet-id&gt;/instances</span>
</pre></div>
</div>
<p>with the arguments as a JSON string in the body:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{ &quot;instances&quot; : &lt;quantity&gt; }</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">flow-id</span></code></td>
<td>Name of the flow</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">flowlet-id</span></code></td>
<td>Name of the flowlet</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">quantity</span></code></td>
<td>Number of instances to be used</td>
</tr>
</tbody>
</table>
<p class="rubric">Examples</p>
<ul>
<li><p class="first">Retrieve the number of instances of the flowlet <em>saver</em> in the flow <em>WhoFlow</em> of the
application <em>HelloWorld</em> in the namespace <em>default</em>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/default/apps/HelloWorld/flows/WhoFlow/flowlets/saver/instances</span>
</pre></div>
</div>
</li>
<li><p class="first">Set the number of instances of the flowlet <em>saver</em> in the flow <em>WhoFlow</em> of the
application <em>HelloWorld</em> in the namespace <em>default</em>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">PUT /v3/namespaces/default/apps/HelloWorld/flows/WhoFlow/flowlets/saver/instances</span>
</pre></div>
</div>
<p>with the arguments as a JSON string in the body:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span> <span class="nt">&quot;instances&quot;</span> <span class="p">:</span> <span class="mi">2</span> <span class="p">}</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="scaling-services">
<h3>Scaling Services<a class="headerlink" href="#scaling-services" title="Permalink to this headline">🔗</a></h3>
<p>You can query or change the number of instances of a service
by using the <code class="docutils literal notranslate"><span class="pre">instances</span></code> parameter with HTTP GET or PUT methods:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/services/&lt;service-id&gt;/instances</span>
<span class="go">PUT /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/services/&lt;service-id&gt;/instances</span>
</pre></div>
</div>
<p>with the arguments as a JSON string in the body:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{ &quot;instances&quot; : &lt;quantity&gt; }</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">service-id</span></code></td>
<td>Name of the service</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">quantity</span></code></td>
<td>Number of instances to be used</td>
</tr>
</tbody>
</table>
<p><strong>Note:</strong> You can scale system services using the Monitor HTTP RESTful API
<a class="reference internal" href="monitor.html#http-restful-api-monitor-scaling-system-services"><span class="std std-ref">Scaling System Services</span></a>.</p>
<p class="rubric">Examples</p>
<ul>
<li><p class="first">Retrieve the number of instances of the service <em>CatalogLookup</em> in the application
<em>PurchaseHistory</em> in the namespace <em>default</em>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/default/apps/PurchaseHistory/services/CatalogLookup/instances</span>
</pre></div>
</div>
</li>
<li><p class="first">Set the number of handler instances of the service <em>RetrieveCounts</em>
of the application <em>WordCount</em>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">PUT /v3/namespaces/default/apps/WordCount/services/RetrieveCounts/instances</span>
</pre></div>
</div>
<p>with the arguments as a JSON string in the body:</p>
<div class="highlight-json-ellipsis notranslate"><div class="highlight"><pre><span></span><span class="p">{</span> <span class="nt">&quot;instances&quot;</span> <span class="p">:</span> <span class="mi">2</span> <span class="p">}</span>
</pre></div>
</div>
</li>
<li><p class="first">Using <code class="docutils literal notranslate"><span class="pre">curl</span></code> and the <a class="reference external" href="../../../developer-manual/getting-started/sandbox/index.html#sandbox-index" title="(in Cask Data Application Platform v6.1.1)"><span class="xref std std-ref">CDAP Sandbox</span></a>:</p>

<script type="text/javascript">

  $(function tabbedparsedliteral5() {
    var tabs = ['linux', 'windows'];
    var mapping = {'windows': 'windows', 'linux': 'linux'};
    var tabSetID = 'linux-windows';
    for (var i = 0; i < tabs.length; i++) {
      var tab = tabs[i];
      $("#tabbedparsedliteral5 .example-tab-" + tab).click(changeExampleTab(tab, mapping, "tabbedparsedliteral5", tabSetID));
    }
  });

</script>
<div id="tabbedparsedliteral5" class="tabbed-parsed-literal dependent-linux-windows">
<ul class="tabbed-parsed-literal nav-tabs">
<li class="example-tab example-tab-linux active"><a href="#">Linux</a></li>
<li class="example-tab example-tab-windows "><a href="#">Windows</a></li>
</ul>

<div class="tab-contents">

<div class="tab-pane tab-pane-linux active">
<div class="code code-tab">
<div class="highlight-console">
<!-- tabbed-parsed-literal start -->
<div class="highlight"><pre><span></span><span class="gp">$</span> curl -w<span class="s2">&quot;\n&quot;</span> -X PUT <span class="s2">&quot;http://localhost:11015/v3/namespaces/default/apps/WordCount/services/RetrieveCounts/instances&quot;</span> <span class="se">\</span>
  -d <span class="s1">&#39;{ &quot;instances&quot; : 2 }&#39;</span></span>
</pre></div>
<!-- tabbed-parsed-literal end --></div>
</div>
</div>
<div class="tab-pane tab-pane-windows ">
<div class="code code-tab">
<div class="highlight-shell-session">
<!-- tabbed-parsed-literal start -->
<div class="highlight"><pre><span></span><span class="gp">&gt;</span> curl -X PUT <span class="s2">&quot;http://localhost:11015/v3/namespaces/default/apps/WordCount/services/RetrieveCounts/instances&quot;</span> ^
<span class="go">  -d &quot;{ \&quot;instances\&quot; : 2 }&quot;</span>
</pre></div>
<!-- tabbed-parsed-literal end --></div>
</div>
</div>
</div>
</div>
</li>
</ul>
</div>
<div class="section" id="scaling-workers">
<h3>Scaling Workers<a class="headerlink" href="#scaling-workers" title="Permalink to this headline">🔗</a></h3>
<p>You can query or change the number of instances of a worker by using the <code class="docutils literal notranslate"><span class="pre">instances</span></code>
parameter with HTTP GET or PUT methods:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workers/&lt;worker-id&gt;/instances</span>
<span class="go">PUT /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workers/&lt;worker-id&gt;/instances</span>
</pre></div>
</div>
<p>with the arguments as a JSON string in the body:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">{ &quot;instances&quot; : &lt;quantity&gt; }</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">worker-id</span></code></td>
<td>Name of the worker</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">quantity</span></code></td>
<td>Number of instances to be used</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<p>Retrieve the number of instances of the worker <em>DataWorker</em> in the application
<em>DemoApp</em> in the namespace <em>default</em>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/default/apps/DemoApp/workers/DataWorker/instances</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="run-records">
<span id="rest-program-runs"></span><h2>Run Records<a class="headerlink" href="#run-records" title="Permalink to this headline">🔗</a></h2>
<p>To see all the runs of a selected program (flows, MapReduce programs, Spark programs,
services, or workflows), issue an HTTP GET to the program’s URL with the <code class="docutils literal notranslate"><span class="pre">runs</span></code>
parameter. This will return a JSON list of all runs for the program, each with a start
time, end time, and program status:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/runs</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflows</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, or <em>workflow</em> being called</td>
</tr>
</tbody>
</table>
<p>You can filter the runs by the status of a program, the start and end times,
and can limit the number of returned records:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Query Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">status</span></code></td>
<td>running/completed/failed</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">start</span></code></td>
<td>start timestamp</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">end</span></code></td>
<td>end timestamp</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">limit</span></code></td>
<td>maximum number of returned records</td>
</tr>
</tbody>
</table>
<p>The result returned will include the <em>runid</em> field, a UUID that uniquely identifies a run within CDAP,
with the start and end times in seconds since the start of the Epoch (midnight 1/1/1970).
Use that runid in subsequent calls to obtain additional information.</p>
<div class="table-block-example container">
<table border="1" class="docutils">
<colgroup>
<col width="99%" />
<col width="1%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">Example: Retrieving Run Records</th>
<td>&#160;</td>
</tr>
</tbody>
</table>
<table border="1" class="triple-table docutils">
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Description</td>
<td>Retrieve the run records of the MapReduce <em>ScoreCounter</em> of the application <em>SportResults</em></td>
</tr>
<tr class="row-even"><td>HTTP Method</td>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/namespaces/default/apps/SportResults/mapreduce/ScoreCounter/runs</span></code></td>
</tr>
<tr class="row-odd"><td>Returns</td>
<td><div class="first last line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">{&quot;runid&quot;:&quot;...&quot;,&quot;start&quot;:1382567598,&quot;status&quot;:&quot;RUNNING&quot;},</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">{&quot;runid&quot;:&quot;...&quot;,&quot;start&quot;:1382567447,&quot;end&quot;:1382567492,&quot;status&quot;:&quot;STOPPED&quot;},</span></code></div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">{&quot;runid&quot;:&quot;...&quot;,&quot;start&quot;:1382567383,&quot;end&quot;:1382567397,&quot;status&quot;:&quot;STOPPED&quot;}</span></code></div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="retrieving-specific-run-information">
<h3>Retrieving Specific Run Information<a class="headerlink" href="#retrieving-specific-run-information" title="Permalink to this headline">🔗</a></h3>
<p>To fetch the run record for a particular run of a program, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/&lt;program-type&gt;/&lt;program-id&gt;/runs/&lt;run-id&gt;</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">flows</span></code>, <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">services</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, or <code class="docutils literal notranslate"><span class="pre">workflows</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the <em>flow</em>, <em>MapReduce</em>, <em>custom service</em>, <em>Spark</em>, or <em>workflow</em> being called</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">run-id</span></code></td>
<td>Run id of the run</td>
</tr>
</tbody>
</table>
<div class="table-block-example container">
<table border="1" class="docutils">
<colgroup>
<col width="99%" />
<col width="1%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">Example: Retrieving A Particular Run Record</th>
<td>&#160;</td>
</tr>
</tbody>
</table>
<table border="1" class="triple-table docutils">
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Description</td>
<td>Retrieve the run record of the MapReduce <em>ScoreCounter</em> of the application <em>SportResults</em>
run <em>b78d0091-da42-11e4-878c-2217c18f435d</em></td>
</tr>
<tr class="row-even"><td>HTTP Method</td>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/namespaces/default/apps/SportResults/mapreduce/ScoreCounter/runs/b78d0091-da42-11e4-878c-2217c18f435d</span></code></td>
</tr>
<tr class="row-odd"><td>Returns</td>
<td><div class="first last line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">{&quot;runid&quot;:&quot;...&quot;,&quot;start&quot;:1382567598,&quot;status&quot;:&quot;RUNNING&quot;}</span></code></div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<p>For services, you can retrieve:</p>
<ul>
<li><p class="first">the history of successfully completed Apache Twill service runs using:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/services/&lt;service-id&gt;/runs?status=completed</span>
</pre></div>
</div>
</li>
</ul>
<p>For workflows, you can retrieve:</p>
<ul>
<li><p class="first">the information about the currently running node(s) in the workflow:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workflows/&lt;workflow-id&gt;/runs/&lt;run-id&gt;/nodes/state</span>
</pre></div>
</div>
</li>
</ul>
<p>More information about workflow endpoint can be found at <a class="reference internal" href="workflow.html#http-restful-api-workflow"><span class="std std-ref">Workflows</span></a></p>
<ul>
<li><p class="first">the schedules defined for a workflow (using the parameter <code class="docutils literal notranslate"><span class="pre">schedules</span></code>):</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workflows/&lt;workflow-id&gt;/schedules</span>
</pre></div>
</div>
</li>
<li><p class="first">the next time that the workflow is scheduled to run (using the parameter <code class="docutils literal notranslate"><span class="pre">nextruntime</span></code>):</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workflows/&lt;workflow-id&gt;/nextruntime</span>
</pre></div>
</div>
</li>
</ul>
<p class="rubric">Examples</p>
<div class="table-block-example container">
<table border="1" class="docutils">
<colgroup>
<col width="99%" />
<col width="1%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">Example: Retrieving The Most Recent Run</th>
<td>&#160;</td>
</tr>
</tbody>
</table>
<table border="1" class="triple-table docutils">
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Description</td>
<td>Retrieve the most recent successful completed run of the service <em>CatalogLookup</em> of the application <em>PurchaseHistory</em></td>
</tr>
<tr class="row-even"><td>HTTP Method</td>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/namespaces/default/apps/PurchaseHistory/services/CatalogLookup/runs?status=completed&amp;limit=1</span></code></td>
</tr>
<tr class="row-odd"><td>Returns</td>
<td><div class="first last line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[{&quot;runid&quot;:&quot;cad83d45-ecfb-4bf8-8cdb-4928a5601b0e&quot;,&quot;start&quot;:1415051892,&quot;end&quot;:1415057103,&quot;status&quot;:&quot;STOPPED&quot;}]</span></code></div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="retrieving-run-records-in-batch">
<h3>Retrieving Run Records in Batch<a class="headerlink" href="#retrieving-run-records-in-batch" title="Permalink to this headline">🔗</a></h3>
<p>To retrieve the latest run records for run records for multiple programs, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/runs</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
</tbody>
</table>
<p>The request body must be a JSON array of objects with the following parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">appId</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">programType</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">workflow</span></code>, <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, or <code class="docutils literal notranslate"><span class="pre">worker</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">programId</span></code></td>
<td>Name of the program (<em>mapreduce</em>, <em>spark</em>, <em>workflow</em>, <em>flow</em>, <em>service</em>, or <em>worker</em>) being called</td>
</tr>
</tbody>
</table>
<p>The response will be an array of Json Objects, each of which will contain the three input parameters
as well as two of three possible extra fields –
“runs”, which is a list of the latest run record for that program,
“statusCode”, which maps to the status code for retrieving the runs for that program,
and “error” if there was an error retrieving runs for that program.
The “statusCode” property will always be included, but “runs” and “error” are mutually exclusive.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">runs</span></code></td>
<td>The latest run records for the program defined by the individual JSON object’s parameters</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">statusCode</span></code></td>
<td>The status code from retrieving the program runs</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">error</span></code></td>
<td>If an error, a description of why the status was not retrieved (for example, the
specified program was not found, or the requested JSON object was missing a parameter)</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Method</th>
<td><code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/v3/namespaces/default/runs</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Body</th>
<td><code class="docutils literal notranslate"><span class="pre">[{&quot;appId&quot;:</span> <span class="pre">&quot;App1&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Service&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;Service1&quot;},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:</span> <span class="pre">&quot;App1&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Workflow&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;testWorkflow&quot;},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:</span> <span class="pre">&quot;App2&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Workflow&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;DataPipelineWorkflow&quot;}]</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">HTTP Response</th>
<td><code class="docutils literal notranslate"><span class="pre">[{&quot;appId&quot;:</span> <span class="pre">&quot;App1&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Service&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;Service1&quot;,</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;statusCode&quot;:</span> <span class="pre">200,</span> <span class="pre">&quot;runs&quot;:</span> <span class="pre">[...]},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:</span> <span class="pre">&quot;App1&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Workflow&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;testWorkflow&quot;,</span> <span class="pre">&quot;statusCode&quot;:</span> <span class="pre">404,</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;error&quot;:</span> <span class="pre">&quot;Program</span> <span class="pre">'testWorkflow'</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">found&quot;},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:</span> <span class="pre">&quot;App2&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Workflow&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;DataPipelineWorkflow&quot;,</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;statusCode&quot;:</span> <span class="pre">200,</span> <span class="pre">&quot;runs&quot;:</span> <span class="pre">[...]]</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Description</th>
<td>Attempt to retrieve the latest run records of the service <em>Service1</em> in the application <em>App1</em>,
the workflow <em>testWorkflow</em> in the application <em>App1</em>
and the workflow <em>DataPipelineWorkflow</em> in the application <em>App2</em>, all in the namespace <em>default</em></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="retrieving-run-counts-in-batch">
<h3>Retrieving Run Counts in Batch<a class="headerlink" href="#retrieving-run-counts-in-batch" title="Permalink to this headline">🔗</a></h3>
<p>To retrieve the run counts for multiple programs, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/runcount</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
</tbody>
</table>
<p>The request body must be a JSON array of objects with the following parameters:</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">appId</span></code></td>
<td>Name of the application being called</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">programType</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">workflow</span></code>, <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, or <code class="docutils literal notranslate"><span class="pre">worker</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">programId</span></code></td>
<td>Name of the program (<em>mapreduce</em>, <em>spark</em>, <em>workflow</em>, <em>flow</em>, <em>service</em>, or <em>worker</em>) being called</td>
</tr>
</tbody>
</table>
<p>The response will be an array of Json Objects, each of which will contain the three input parameters
as well as two of three possible extra fields –
“runCount”, which is count for the program run,
“statusCode”, which maps to the status code for retrieving the run count for that program,
and “error” if there was an error retrieving runs for that program.
The “statusCode” property will always be included, but “runCount” and “error” are mutually exclusive.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">runCount</span></code></td>
<td>The number of program runs for the program defined by the individual JSON object’s parameters</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">statusCode</span></code></td>
<td>The status code from retrieving the program run count</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">error</span></code></td>
<td>If an error, a description of why the status was not retrieved (for example, the
specified program was not found, or the requested JSON object was missing a parameter)</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Method</th>
<td><code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/v3/namespaces/default/runcount</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Body</th>
<td><code class="docutils literal notranslate"><span class="pre">[{&quot;appId&quot;:</span> <span class="pre">&quot;App1&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Service&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;Service1&quot;},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:</span> <span class="pre">&quot;App1&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Workflow&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;testWorkflow&quot;},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:</span> <span class="pre">&quot;App2&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Workflow&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;DataPipelineWorkflow&quot;}]</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">HTTP Response</th>
<td><code class="docutils literal notranslate"><span class="pre">[{&quot;appId&quot;:</span> <span class="pre">&quot;App1&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Service&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;Service1&quot;,</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;statusCode&quot;:</span> <span class="pre">200,</span> <span class="pre">&quot;runCount&quot;:</span> <span class="pre">20},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:</span> <span class="pre">&quot;App1&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Workflow&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;testWorkflow&quot;,</span> <span class="pre">&quot;statusCode&quot;:</span> <span class="pre">404,</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;error&quot;:</span> <span class="pre">&quot;Program</span> <span class="pre">'testWorkflow'</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">found&quot;},</span></code>
<code class="docutils literal notranslate"><span class="pre">{&quot;appId&quot;:</span> <span class="pre">&quot;App2&quot;,</span> <span class="pre">&quot;programType&quot;:</span> <span class="pre">&quot;Workflow&quot;,</span> <span class="pre">&quot;programId&quot;:</span> <span class="pre">&quot;DataPipelineWorkflow&quot;,</span></code>
<code class="docutils literal notranslate"><span class="pre">&quot;statusCode&quot;:</span> <span class="pre">200,</span> <span class="pre">&quot;runCount&quot;:</span> <span class="pre">300}]</span></code></td>
</tr>
<tr class="row-even"><th class="stub">Description</th>
<td>Attempt to retrieve the run count of the service <em>Service1</em> in the application <em>App1</em>,
the workflow <em>testWorkflow</em> in the application <em>App1</em>
and the workflow <em>DataPipelineWorkflow</em> in the application <em>App2</em>, all in the namespace <em>default</em></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="retrieving-specific-run-count">
<h3>Retrieving Specific Run Count<a class="headerlink" href="#retrieving-specific-run-count" title="Permalink to this headline">🔗</a></h3>
<p>To fetch the run count for a particular program, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">GET /v3/namespaces/&lt;namespace-id&gt;/apps/{app-id}/{program-type}/{program-id}/runcount</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">program-type</span></code></td>
<td>One of <code class="docutils literal notranslate"><span class="pre">mapreduce</span></code>, <code class="docutils literal notranslate"><span class="pre">spark</span></code>, <code class="docutils literal notranslate"><span class="pre">workflow</span></code>, <code class="docutils literal notranslate"><span class="pre">flow</span></code>, <code class="docutils literal notranslate"><span class="pre">service</span></code>, or <code class="docutils literal notranslate"><span class="pre">worker</span></code></td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">program-id</span></code></td>
<td>Name of the program (<em>mapreduce</em>, <em>spark</em>, <em>workflow</em>, <em>flow</em>, <em>service</em>, or <em>worker</em>) being called</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">HTTP Method</th>
<td><code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/v3/namespaces/default/apps/myApp/workflows/DataPipelineWorkflow/runcount</span></code></td>
</tr>
<tr class="row-even"><th class="stub">HTTP Response</th>
<td><code class="docutils literal notranslate"><span class="pre">[20]</span></code></td>
</tr>
<tr class="row-odd"><th class="stub">Description</th>
<td>Retrieve the run count of the workflow <em>DataPipelineWorkflow</em> of the application <em>myApp</em></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="workflow-runs-suspend-and-resume">
<span id="http-restful-api-lifecycle-workflow-runs-suspend-resume"></span><h3>Workflow Runs: Suspend and Resume<a class="headerlink" href="#workflow-runs-suspend-and-resume" title="Permalink to this headline">🔗</a></h3>
<p>For workflows, in addition to <a class="reference internal" href="#http-restful-api-lifecycle-start"><span class="std std-ref">starting</span></a> and
<a class="reference internal" href="#http-restful-api-lifecycle-stop"><span class="std std-ref">stopping</span></a>, you can suspend and resume individual
runs of a workflow using the RESTful API.</p>
<p><strong>Suspend:</strong> To <em>suspend</em> means that the current activity will be taken to completion, but no further
programs will be initiated. Programs will not be left partially uncompleted, barring any errors.</p>
<p>In the case of a workflow with multiple MapReduce programs, if one of them is running (first of
three perhaps) and you suspend the workflow, that first MapReduce will be completed but the
following two will not be started.</p>
<p><strong>Resume:</strong> To <em>resume</em> means that activity will start up where it was left off, beginning with the start
of the next program in the sequence.</p>
<p>In the case of the workflow mentioned above, resuming it after suspension would start up with the
second of the three MapReduce programs, which is where it would have left off when it was suspended.</p>
<p>With workflows, <em>suspend</em> and <em>resume</em> require a <em>run-id</em> as the action takes place on
either a currently running or suspended workflow.</p>
<p>To suspend or resume a workflow, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workflows/&lt;workflow-id&gt;/runs/&lt;run-id&gt;/suspend</span>
<span class="go">POST /v3/namespaces/&lt;namespace-id&gt;/apps/&lt;app-id&gt;/workflows/&lt;workflow-id&gt;/runs/&lt;run-id&gt;/resume</span>
</pre></div>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="80%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">namespace-id</span></code></td>
<td>Namespace ID</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">app-id</span></code></td>
<td>Name of the application</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">workflow-id</span></code></td>
<td>Name of the workflow</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">run-id</span></code></td>
<td>UUID of the workflow run</td>
</tr>
</tbody>
</table>
<div class="table-block-example container">
<table border="1" class="docutils">
<colgroup>
<col width="99%" />
<col width="1%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><th class="stub">Example: Suspending a Workflow</th>
<td>&#160;</td>
</tr>
</tbody>
</table>
<table border="1" class="triple-table docutils">
<colgroup>
<col width="15%" />
<col width="85%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Description</td>
<td>Suspends the run <code class="docutils literal notranslate"><span class="pre">0ce13912-e980-11e4-a7d7-8cae4cfd0e64</span></code> of the workflow
<em>PurchaseHistoryWorkflow</em> of the application <em>PurchaseHistory</em></td>
</tr>
<tr class="row-even"><td>HTTP Method</td>
<td><code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/v3/namespaces/default/apps/PurchaseHistory/workflows/PurchaseHistoryWorkflow/runs/0ce13912-e980-11e4-a7d7-8cae4cfd0e64/suspend</span></code></td>
</tr>
<tr class="row-odd"><td>Returns</td>
<td><div class="first last line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">Program</span> <span class="pre">run</span> <span class="pre">suspended.</span></code> if successfully set as suspended</div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>

</div>
    <div class="col-md-2">
      <div id="right-sidebar" class="bs-sidenav scrollable-y" role="complementary">
        <div id="localtoc-scrollspy">
        </div>
      </div>
    </div></div>
</div>
<!-- block main content end -->
<!-- block footer -->
<footer class="footer">
      <div class="container">
        <div class="row">
          <div class="col-md-2 footer-left"><a title="Dataset HTTP RESTful API" href="dataset.html" />Previous</a></div>
          <div class="col-md-8 footer-center"><a class="footer-tab-link" href="../table-of-contents/../../reference-manual/licenses/index.html">Copyright</a> &copy; 2014-2020 Cask Data, Inc.&bull; <a class="footer-tab-link" href="//docs.cask.co/cdap/6.1.1/cdap-docs-6.1.1-web.zip" rel="nofollow">Download</a> an archive or
<a class="footer-tab-link" href="//docs.cask.co/cdap">switch the version</a> of the documentation
          </div>
          <div class="col-md-2 footer-right"><a title="Logging HTTP RESTful API" href="logging.html" />Next</a></div>
        </div>
      </div>
    </footer>
<!-- block footer end -->
<script type="text/javascript" src="../_static/bootstrap-3.3.6/js/bootstrap.min.js"></script><script type="text/javascript" src="../_static/js/bootstrap-sphinx.js"></script><script type="text/javascript" src="../_static/js/abixTreeList-2.js"></script><script type="text/javascript" src="../_static/js/cdap-dynamicscrollspy-4.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script><script type="text/javascript" src="../_static/js/copy-to-clipboard.js"></script><script type="text/javascript" src="../_static/js/jquery.mousewheel.min.js"></script><script type="text/javascript" src="../_static/js/jquery.mCustomScrollbar.js"></script><script type="text/javascript" src="../_static/js/js.cookie.js"></script><script type="text/javascript" src="../_static/js/tabbed-parsed-literal-0.2.js"></script><script type="text/javascript" src="../_static/js/cdap-onload-javascript.js"></script><script type="text/javascript" src="../_static/js/cdap-version-menu.js"></script>
    <script src="https://cdap.gitee.io/docs/cdap/json-versions.js"/></script>
  </body>
</html>